package com.fortify.awb;

/**
 * This interface extends the {@link BugtrackerPlugin} interface.  You should use this interface if your
 * custom bug tracker requires an authenticated connection for bug submission.  For instance, you may
 * need to connect to the central repository before you can submit a bug, and disconnect when the
 * submission is complete.
 * <br><br>
 * When the user attempts to file a bug, Fortify's bug tracker framework will first call the {@link #isConnected()}
 * method.  If that returns true, the bug tracker workflow will proceed as normal.  If {@link #isConnected()}
 * returns false, the framework will call the {@link #connect()} method, which should provide a means for
 * users to enter in their authentication information, and authenticate against the repository.  If {@link #connect()}
 * returns true, {@link #isConnected()} should return true until {@link #disconnect()} is called.
 */

public interface ConnectionBasedBugtrackerPlugin extends BugtrackerPlugin {

	/**
	 * Connect to the bug tracker repository.
	 * <br><br>
	 * This method will be called when a user attempts to file a bug, and {@link #isConnected()}
	 * returns false.  You should allow users to input authentication information, and you should use
	 * that information to authenticate against the repository.
	 * @return true if the connection attempt was successful, false otherwise
	 */
	boolean connect();

	/**
	 * This method will be called each time a user attempts to file a bug to determine if
	 * {@link #connect()} needs to be called.
	 * @return true if we have an open connection to the bug tracker repository (via a call to
	 * {@link #connect()}), false otherwise.
	 */
	boolean isConnected();

	/**
	 * Disconnect from the bug tracker repository.
	 * @return true if the disconnect attempt was successful, false otherwise.
	 */
	boolean disconnect();
}